feat: Add asyncio capture client by marandaneto · Pull Request #719 · PostHog/posthog-python

marandaneto · 2026-07-01T13:02:59Z

💡 Motivation and Context

Starts the stacked implementation for #103 by adding an asyncio-native client for event capture. This introduces AsyncClient / AsyncPosthog, async HTTP helpers, and an asyncio queue/consumer pipeline so async applications can enqueue and flush events without daemon threads.

This first PR intentionally focuses on the capture lifecycle and API shape. Async feature flag evaluation is stacked in the next PR. Review feedback was addressed by removing sensitive request/response payloads from async debug logs, running temporary sync flag fallback calls off the event loop, and parameterizing identify-method enqueue coverage.

💚 How did you test it?

uv run ruff check posthog/async_client.py posthog/test/test_async_client.py
uv run ruff check posthog/async_request.py posthog/test/test_async_request.py
uv run --extra test pytest posthog/test/test_async_client.py posthog/test/test_async_request.py --verbose --timeout=30
uv run python -W error -c "import posthog; from posthog import AsyncPosthog"
uv run --extra dev python .github/scripts/check_public_api.py

📝 Checklist

I reviewed the submitted code.
I added tests to verify the changes.
I updated the docs if needed.
No breaking change or entry added to the changelog.

If releasing new changes

Ran sampo add to generate a changeset file

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Implemented with pi. The stack is split so reviewers can first inspect the async capture/queue/request foundation, then the async feature flag layer, then docs. httpx is added as an optional posthog[async] dependency and imported lazily so normal import posthog still works without the extra.

github-actions · 2026-07-01T13:06:35Z

posthog-python Compliance Report

Date: 2026-07-02 14:11:02 UTC
Duration: 177225ms

✅ All Tests Passed!

46/46 tests passed

Capture Tests

✅ 29/29 tests passed

View Details

Test	Status	Duration
Format Validation.Event Has Required Fields	✅	518ms
Format Validation.Event Has Uuid	✅	1507ms
Format Validation.Event Has Lib Properties	✅	1506ms
Format Validation.Distinct Id Is String	✅	1507ms
Format Validation.Token Is Present	✅	1507ms
Format Validation.Custom Properties Preserved	✅	1508ms
Format Validation.Event Has Timestamp	✅	1507ms
Retry Behavior.Retries On 503	✅	9515ms
Retry Behavior.Does Not Retry On 400	✅	3510ms
Retry Behavior.Does Not Retry On 401	✅	3508ms
Retry Behavior.Respects Retry After Header	✅	9514ms
Retry Behavior.Implements Backoff	✅	23528ms
Retry Behavior.Retries On 500	✅	7506ms
Retry Behavior.Retries On 502	✅	7512ms
Retry Behavior.Retries On 504	✅	7513ms
Retry Behavior.Max Retries Respected	✅	23519ms
Deduplication.Generates Unique Uuids	✅	1509ms
Deduplication.Preserves Uuid On Retry	✅	7513ms
Deduplication.Preserves Uuid And Timestamp On Retry	✅	14515ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	✅	7515ms
Deduplication.No Duplicate Events In Batch	✅	1504ms
Deduplication.Different Events Have Different Uuids	✅	1507ms
Compression.Sends Gzip When Enabled	✅	1507ms
Batch Format.Uses Proper Batch Structure	✅	1506ms
Batch Format.Flush With No Events Sends Nothing	✅	1006ms
Batch Format.Multiple Events Batched Together	✅	1505ms
Error Handling.Does Not Retry On 403	✅	3508ms
Error Handling.Does Not Retry On 413	✅	3508ms
Error Handling.Retries On 408	✅	7515ms

Feature_Flags Tests

✅ 17/17 tests passed

View Details

Test	Status	Duration
Request Payload.Request With Person Properties Device Id	✅	1004ms
Request Payload.Flags Request Uses V2 Query Param	✅	1006ms
Request Payload.Flags Request Hits Flags Path Not Decide	✅	1006ms
Request Payload.Flags Request Omits Authorization Header	✅	1007ms
Request Payload.Token In Flags Body Matches Init	✅	1007ms
Request Payload.Groups Round Trip	✅	1006ms
Request Payload.Groups Default To Empty Object	✅	1007ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False	✅	1006ms
Request Payload.Disable Geoip Omitted Defaults To False	✅	1007ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key	✅	1007ms
Request Lifecycle.No Flags Request On Init Alone	✅	503ms
Request Lifecycle.No Flags Request On Normal Capture	✅	1509ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests	✅	1011ms
Request Lifecycle.Mock Response Value Is Returned To Caller	✅	1002ms
Retry Behavior.Retries Flags On 502	✅	1007ms
Retry Behavior.Retries Flags On 504	✅	1006ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event	✅	1510ms

greptile-apps · 2026-07-01T13:08:44Z

Comments Outside Diff (1)

posthog/async_client.py, line 661-665 (link)

Poller.stop() blocks the event loop during shutdown

Poller.stop() calls self.join() on its underlying threading.Thread. If the poller thread is in the middle of executing a feature-flag poll request when shutdown() is called, this join() will block the event loop for up to feature_flags_request_timeout_seconds (default 3 s). The same risk applies to _shutdown_flag_definition_cache_provider() and _unregister_duplicate_client() if they perform any I/O or lock acquisition. Consider wrapping these with await asyncio.get_event_loop().run_in_executor(None, self.poller.stop) (and equivalents) so the event loop remains responsive during teardown.

_{Reviews (1): Last reviewed commit: "Avoid logging async request payloads" | Re-trigger Greptile}

marandaneto · 2026-07-02T12:10:38Z

Addressed the Greptile shutdown feedback in 43e6275 — async shutdown now offloads the inherited blocking cleanup path (Poller.stop(), flag cache provider shutdown, duplicate-client unregister) via asyncio.to_thread, with test coverage.

Add asyncio capture client

b9fb7fc

marandaneto self-assigned this Jul 1, 2026

marandaneto mentioned this pull request Jul 1, 2026

feat: Add async feature flag evaluation #720

Draft

5 tasks

github-advanced-security AI found potential problems Jul 1, 2026

View reviewed changes

Comment thread posthog/async_request.py Fixed

Comment thread posthog/_async_request.py Fixed

Avoid logging async request payloads

7ca95dc

greptile-apps Bot reviewed Jul 1, 2026

View reviewed changes

Comment thread posthog/async_client.py Outdated

Comment thread posthog/test/test_async_client.py Outdated

marandaneto added 3 commits July 1, 2026 15:11

Address async capture review feedback

a6c990f

Fix async client mypy violations

e4ad868

Avoid dynamic success log messages

f90c90c

github-advanced-security AI found potential problems Jul 2, 2026

View reviewed changes

Comment thread posthog/_async_request.py Fixed

marandaneto force-pushed the async-sdk-01-capture branch 2 times, most recently from 8816f29 to cfe5d0f Compare July 2, 2026 11:25

Hide async internals from public API

3b1a554

marandaneto force-pushed the async-sdk-01-capture branch from cfe5d0f to 3b1a554 Compare July 2, 2026 11:28

Address async capture CI feedback

43e6275

marandaneto added 2 commits July 2, 2026 15:07

Refactor shared event preparation

bf32965

Merge remote-tracking branch 'origin/main' into async-sdk-01-capture

1007bfb

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: Add asyncio capture client#719

feat: Add asyncio capture client#719
marandaneto wants to merge 9 commits into
mainfrom
async-sdk-01-capture

marandaneto commented Jul 1, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jul 1, 2026 •

edited

Loading

Uh oh!

greptile-apps Bot commented Jul 1, 2026 •

edited

Loading

Comments Outside Diff (1)

Uh oh!

Uh oh!

Uh oh!

Uh oh!

marandaneto commented Jul 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

marandaneto commented Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

💡 Motivation and Context

💚 How did you test it?

📝 Checklist

If releasing new changes

🤖 Agent context

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

posthog-python Compliance Report

✅ All Tests Passed!

Capture Tests

Feature_Flags Tests

Uh oh!

greptile-apps Bot commented Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Comments Outside Diff (1)

Uh oh!

Uh oh!

Uh oh!

Uh oh!

marandaneto commented Jul 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

marandaneto commented Jul 1, 2026 •

edited

Loading

github-actions Bot commented Jul 1, 2026 •

edited

Loading

greptile-apps Bot commented Jul 1, 2026 •

edited

Loading